<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"

    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US"

xml:lang="en-US">

<head>

<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

<meta name="keywords"

content="webcp, web, webhost, webhosting, controlpanel, cpanel, control, panel, php, freebsd, mysql, dns, email, http, httpd, isp, internet, service, provider, manage, management, customer, client, remote, gui, interface, backend, server, frontend, connect, login, log, in, shell, provide" />

<meta name="description"

content="This document provides a guide to installing and configuring the web control panel, webcp, on the FreeBSD platform" />

<meta name="robots" content="all" />



<title>Installing and Configuring web-cp on FreeBSD</title>



<link rel="stylesheet" type="text/css" href="/StyleSheets/home.css" />



<style type="text/css">

<!--

html, body { background: #fff; color: #000; }

html, body, h2, h3, h4, div, p, ul, li, input {

   font-family: Arial, Helvetica, sans-serif;

}

h1{font-size:14pt; background-color:#999999}

h2{font-size:12pt}

h3{font-size:10pt}

body{font-size:8pt}

-->



</style>

</head>

<body>

<h1>Installing and Configuring web-cp on FreeBSD</h1>

<h2>Introduction</h2>

<p>

This is a short article covering the steps required to install and

configure <a href="http://webcp.can-host.com">web-cp</a> on

<a href="http://www.freebsd.org/">FreeBSD</a>.

</p>



<p>

These are only the steps I took to get <a href="http://webcp.can-host.com">web-cp</a> working on my server at

the time of writing.  Since the code is still in beta, obviously this

text has a very short shelf-life.  YMMV.

</p>



<p>

Further, as is noted on the web-cp site, web-cp is not a trivial

application to install and should not be attempted unless YOU UNDERSTAND

EVERY COMMAND YOU EXECUTE AND THE IMPLICATIONS OF DOING SO.

</p>



<p>

As a generalized acid-test, if you have spent less than 1000 hours total

time configuring apache, php, named, sendmail (or similar), writing php,

administering mysql/postgresql (&lt;add others here!&gt;) - then you will have

a hard time installing and configuring <a href="http://webcp.can-host.com">web-cp</a>.  If you have over 1000

hours total 'flight-time', you'll have a great time (in a masochistic kind of way:).<br />

[EDIT 22/07/2003: this is actually not a joke, but if you have lots of enthusiasm

and always RESEARCH YOUR PROBLEMS BEFORE ASKING FOR HELP, then you can

probably half the above estimates and get along fine!]

</p>



<h3>Notes:</h3>

<ul>

<li>

Non-SSL apache install.<br />

[EDIT 22/07/2003: this is somewhat outdated now by the excellent webcp-httpd.php

PHP httpd daemon.  Yes, you read correctly, a PHP httpd daemon!  This is

still very much in beta but 

</li>

<li>

Commands executed as UID 0 in a csh shell, unless otherwise stated.

</li>

</ul>



<h2>Download and Extract the web-cp tarball</h2>

<h3>Download the webcp tarball</h3>

<p>

Fetch the web-cp tarball from Uncle Felix's server.  At the time of writing

the current version of web-cp is 0.5.1.

</p>

<p>The current tarball can be obtained here:<br />

<a href="http://webcp.can-host.com/webcp-0.5.1.tar.gz">webcp-0.5.1.tar.gz</a></p>



<p>

To fetch the tarball directly from your shell:

</p>



<p><code>

root@users /root# cd /usr/local

root@users /usr/local# <a href="http://www.munk.nu/index.php?action=man&amp;manpage=fetch&amp;section=0">fetch</a> <a href="http://webcp.can-host.com/webcp-0.5.1.tar.gz">webcp-0.5.1.tar.gz</a></code></p>



<h3>Extract the web-cp tarball</h3>

<p>

The tarball will be extracted into it's own directory, /usr/local/webcp:

</p>



<p><code>

root@users /usr/local# <a href="http://www.munk.nu/index.php?action=man&amp;manpage=tar&amp;section=0">tar</a> zxvf <a href="http://webcp.can-host.com/webcp-0.5.1.tar.gz">webcp-0.5.1.tar.gz</a>webcp/

webcp/CVS/

webcp/CVS/Root

&lt;snip&gt;</code></p>



<h3>IMPORTANT NOTE ON GETTING THE LATEST VERSION OF WEBCP</h3>

<p>

At the time of writing, web-cp is a constantly evolving beaast.  As such

it is important that you update your source tarball to the latest version

using the CVS repository. Details of the CVS repository can be found on the 

<a href="http://webcp.can-host.com">web-cp</a> site.

</p>

<p>

Using CVS from a shell to checkout and track the webcp CVS source code is covered 

in <a href="#webcp_cvs">Appendix A - Using CVS to track web-cp source</a>

</p>



<h2>Add a webcp user to the system</h2>

<p>

<b>WARNING - ensure uid 81 isn't already taken!</b>

</p>

<p>

Execute the following command to add a 'webcp' user to the system:

</p>



<p><code>

<a href="http://www.munk.nu/index.php?action=man&amp;manpage=pw&amp;section=0">pw</a> adduser -n webcp -u 81 -d /usr/local/webcp -s /sbin/nologin

</code></p>



<p>

Ensure that the password field for webcp is set to '*' (use 'vipw').

This is an additional precaution in addition to setting the shell to

/sbin/nologin to ensure illegal logins to the 'webcp' cannot occur.

</p>



<h2>Change permissions on /usr/local/webcp</h2>

<p>

In general, follow the instructions in the

<a href="http://webcp-devel.can-host.com/cvsweb.cgi/~checkout~/webcp/INSTALL?content-type=text/plain">INSTALL</a> file

regarding permissions.

</p>





<h2>Modify the configuration files for web-cp</h2>

<p><code>cp /usr/local/webcp/web/<a href="http://webcp-devel.can-host.com/cvsweb.cgi/~checkout~/webcp/config-freebsd.inc.phps?content-type=text/plain">config-freebsd.inc.phps</a> /usr/local/webcp/web/config.inc.php</code></p>



<p>and make any changes to /usr/local/webcp/web/config.inc.php to suit your server.</p>



<p>Note: this file is available here:</p>



<p><a href="http://webcp-devel.can-host.com/cvsweb.cgi/~checkout~/webcp/config-freebsd.inc.phps?content-type=text/plain">config-freebsd.inc.phps</a></p>



<h2>Configure apache for web-cp</h2>

<p>

To recognize the new sites that <a href="http://webcp.can-host.com">web-cp</a> adds to the system, the main apache configuration file - httpd.conf - must be configured to include the file /usr/local/webcp/httpd/include/include.httpd.</p>



<p>Add a line at the end of your main apache httpd.conf file /usr/local/etc/apache/httpd.conf to include the webcp httpd include config:</p>



<p><code>Include /usr/local/webcp/httpd/include/include.httpd</code></p>



<p>

This will allow the regular httpd to include vhosts added by webcp.

</p>



<h2>Installing the PHP Command-LIne (CLI) binary for web-cp</h2>

<p>

The <a href="http://webcp.can-host.com">web-cp</a> backend server - <a href="http://webcp-devel.can-host.com/cvsweb.cgi/~checkout~/webcp/server/webcp.php?content-type=text/plain">server/webcp.php</a> - and the <a href="http://webcp.can-host.com">web-cp</a> httpd server - <a href="http://webcp-devel.can-host.com/cvsweb.cgi/~checkout~/webcp/server/webcp-httpd.php?content-type=text/plain">server/webcp-httpd.php</a> - both require that PHP be built as a CLI binary with various options so it can control/manipulate system processes.  Rather than attempt to build and install this binary with these special options into the system proper - which might disrupt or modify an existing installation of PHP - instead we build the PHP CLI binary from the source PHP tarball and install it into /usr/local/webcp/php.

</p>

<p>

In the instructions below you will need to adjust your commands to obtain the latest current stable source release.

</p>



<h3>Obtaining and Extracting the PHP source tarball</h3>

<p>

Download the PHP source tarball into a temporary location away from the webcp folder.  The best thing to do is create a subdirectory in your home directory called 'php' and download/extract the source to there:

</p>



<p><code>

root@users /home/munk# mkdir php

root@users /home/munk# cd php

root@users /home/munk/php# fetch -o php-4.3.2.tar.bz2 http://uk.php.net/get/php-4.3.2.tar.bz2/from/this/mirror



&lt;snip&gt;

root@users /home/munk/php# tar zyvf php-4.3.2.tar.bz2



&lt;snip&gt;

root@users /home/munk/php# cd php-4.3.2

root@users /home/munk/php/php-4.3.2#

</code></p>



<p>

<b>Note:</b><br />

The PHP Download page is located here:<br />

<a href="http://www.php.net/downloads.php">PHP Download Page</a>

</p>



<h3>Building and Installing the PHP CLI binary</h3>

<p>

From the shell in the base directory of the tarball distribution we extracted above, execute the following 'configure' command line:

</p>



<p><code>

./configure \

--enable-versioning \

--enable-memory-limit \

--with-layout=GNU \

--with-zlib-dir=/usr \

--disable-all \

--enable-discard-path \

--enable-ctype \

--with-mysql=/usr/local \

--enable-pcntl \

--with-pcre-regex=yes \

--enable-posix \

--enable-session \

--enable-sockets \

--enable-tokenizer \

--enable-xml \

--with-expat-dir=/usr/local \

--with-zlib=yes \

--prefix=/usr/local/webcp/php

</code></p>



<p>

This will configure PHP with options suitable for <a href="http://webcp.can-host.com">web-cp</a>.

</p>



<p>

Next, create a directory to install PHP into:

</p>



<p><code>

root@users /home/munk/php/php-4.3.2# mkdir /usr/local/webcp/php

</code></p>



<p>

Finally, build and install PHP by issuing the following command:

</p>



<p><code>

root@users /home/munk/php/php-4.3.2# make

root@users /home/munk/php/php-4.3.2# make install-cli

</code></p>



<p>This will install a directory tree under /usr/local/webcp/php containing the standalone php cli binary that will be used for the <a href="http://webcp.can-host.com">web-cp</a> backend servers.

</p>



<h2>Modify the webcp.php script to reflect the path to the php CLI binary</h2>

<p>Change the shebang line in <code>/usr/local/webcp/server/webcp.php</code> to:</p>



<p><code>#!/usr/local/webcp/php/bin/php -q</code></p>





<h2>Copy the webcp.sh rc init script into /usr/local/etc/rc.d</h2>

<p>

To ensure the <a href="http://webcp.can-host.com">web-cp</a> backend server - <a href="http://webcp-devel.can-host.com/cvsweb.cgi/~checkout~/webcp/server/webcp.php?content-type=text/plain">server/webcp.php</a> - and the <a href="http://webcp.can-host.com">web-cp</a> httpd server - <a href="http://webcp-devel.can-host.com/cvsweb.cgi/~checkout~/webcp/server/webcp-httpd.php?content-type=text/plain">server/webcp-httpd.php</a> - both start when your system boots, copy and make executable the rc init scripts located in /usr/local/webcp/contrib/freebsd:

</p>



<p><code>

root@users /home/munk/php/php-4.3.2# cd /usr/local/etc/rc.d

root@users /usr/local/etc/rc.d# cp /usr/local/webcp/contrib/freebsd/webcp.sh ./

root@users /usr/local/etc/rc.d# cp /usr/local/webcp/contrib/freebsd/webcp-httpd.sh ./

root@users /usr/local/etc/rc.d# chmod +x webcp.sh webcp-httpd.sh

</code></p>



<p>

<b>Note:</b><br />

These files are available online here:<br />

<a href="http://munk.nu/webcp/webcp.sh">http://munk.nu/webcp/webcp.sh</a><br />

<a href="http://munk.nu/webcp/webcp-httpd.sh">http://munk.nu/webcp/webcp-httpd.sh</a><br />

</p>



<h2>Start the webcp.php backend server</h2>

<p>

To save rebooting, start the <a href="http://webcp.can-host.com">web-cp</a> servers from the command line:

</p>



<p><code>

root@users /usr/local/webcp/server# /usr/local/etc/rc.d/webcp.sh start

root@users /usr/local/webcp/server# /usr/local/etc/rc.d/webcp-httpd.sh start

</code></p>



<h2>Creating an initial web-cp reseller account</h2>

<p>

Finally, in a browser browse to the $cfg["sysname"]:$cfg["port"] location you specified in your <a href="http://webcp.can-host.com">web-cp</a> configuration file - ie http://example.com:81/ where you will be prompted to complete a form to create the initial <a href="http://webcp.can-host.com">web-cp</a> user.

</p>

<p>

After clicking submit you will be told that new accounts/domains have been created and you can login to your webcp panel for the first time!  See the online docs for help.

</p>

















<div><a name="webcp_cvs"></a></div>

<h2>Appendix A - Using CVS to track web-cp source</h2>

<h2>Set your $CVSROOT environment variable</h2>

<p>

<a href="http://www.munk.nu/index.php?action=man&amp;manpage=cvs&amp;section=0">cvs</a> is commonly available by default on most flavours of Unix -

certainly those flavours currently supported by <a href="http://webcp.can-host.com">web-cp</a>.  Before using 

<a href="http://www.munk.nu/index.php?action=man&amp;manpage=cvs&amp;section=0">cvs</a> to manipulate the webcp CVS repository it is best to set your 

<a href="http://munk.nu/doc/local_share_doc/cvsbook/cvsbook.html#_CVSROOT">$CVSROOT</a> shell environment variable.  This will save you 

a lot of typing when using cvs.

</p>



<p><code>

root@users /usr/local/webcp# setenv CVSROOT :pserver:nobody@webcp-devel.can-host.com:2401/var/lib/cvsroot

</code></p>



<p>

With the $CVSROOT variable set in your shell, you do not have to type:

</p>

<p><code>-d :pserver:nobody@webcp-devel.can-host.com:2401/var/lib/cvsroot</code></p>

<p>

when issuing the cvs commands below.

</p>



<h2>Logging into CVS</h2>

<p>

With $CVSROOT set as above, logging into the webcp CVS repository is as easy as:

</p>



<p><code>

root@users /usr/local/webcp# cvs login

Logging in to

:pserver:nobody@webcp-devel.can-host.com:2401/var/lib/cvsroot

CVS password: &lt;hit enter here&gt;

</code></p>



<p>

Note in the above that no password is required for access to the webcp 

CVS repository as the 'nobody' user.

</p>



<h2>Checking out the latest version of the web-cp source from CVS</h2>

<p>

To obtain a local copy of the web-cp source from the CVS repository,

issue the cvs 'checkout' command, followed by the module name 'webcp'. 

</p>



<p>

This will create a directory called 'webcp' in your current working directory 

and populate that directory with the latest version of the web-cp source files 

from the CVS repository.  A good tip here is to create a 'cvs' directory in your 

regular user's directory, change to that directory and then issue the checkout 

command:

</p>

<p><code>

root@users /usr/local/webcp# cd /home/munk

root@users /home/munk# mkdir cvs

root@users /home/munk# cd cvs

root@users /home/munk/cvs# cvs checkout webcp

&lt;snip&gt;</code></p>



<p>

In this way you can easily track differences between your 'production' code and 

the version currently up to date in CVS.

</p>





<h2>Keeping up to date with CVS updates</h2>

<h3>Subscribing on the web-cp forum for CVS update notification</h3>

<p>

Updates to the web-cp repository are made regularly.  To keep abreast of the latest

changes to the CVS repository you can ask to be added to the CVS mailing list:

</p>

<ul>

<li>

Register on the 

<a href="http://webcp.can-host.com/phpBB/index.php">web-cp forum</a>.

</li>

<li>

Reply to the following topic:<br />

<a href="http://webcp.can-host.com/phpBB/viewtopic.php?t=463">

	CVS commit mailing list

</a>

<br />

with a reply such as 'subscribe me please' - please never goes amiss!

</li>

</ul>



<p>

Once added - courtesy of Felix - you will receive notification by email whenever 

the CVS repository is updated.

</p>



<h3>Updating your local copy of the CVS source files using cvs</h3>

<p>

To update your copy of the source files to the latest version in the CVS 

repository, change into the directory containing your local version of the source 

files and issue the cvs 'update' command:

</p>



<p><code>

root@users /home/munk/cvs# cd webcp

root@users /home/munk/cvs/webcp# cvs update

</code></p>



<h3>A Warning about cvs update - and a nice intro to the cvs status command</h3>

<p>

cvs update involves checking every single file in the repository 

against your locally stored version information and can take some time if you 

are on a slow connection.  With this in mind you can use the cvs 'status' command 

to check if any files need updating:

</p>



<p><tt>

root@users /home/munk/cvs/webcp# cvs status



&lt;snip&gt;

File: FEATURES          Status: Up-to-date 



   Working revision:    1.2

   Repository revision: 1.2     /var/lib/cvsroot/webcp/FEATURES,v

   Sticky Tag:          (none)

   Sticky Date:         (none)

   Sticky Options:      (none)



===================================================================

File: HELP              Status: Up-to-date



&lt;snip&gt;

cvs server: server/lib/linux-domain.wcp.phps is no longer in the repository



&lt;snip&gt;

===================================================================

File: domain.wcp.phps   Status: Needs Patch



   Working revision:    1.1

   Repository revision: 1.3     /var/lib/cvsroot/webcp/server/lib/domain.wcp.phps,v

   Sticky Tag:          (none)

   Sticky Date:         (none)

   Sticky Options:      (none)



===================================================================

</tt></p>



<p>

From the snippet above we can note several things:

</p>

<ul>

<li>

the file 'FEATURES' is up to date - we don't need to do anything to this file

</li>

<li>

the file 'linux-domain.wcp.phps' is no longer in the online CVS repo - 

we could remove this from our local system without problem

</li>

<li>

the file 'domain.wcp.phps' on the CVS repository is more up to date than 

our local version - we need to update this file

</li>

</ul>



<h3>Another cvs update warning - and a nice intro to the cvs diff command</h3>

<p>

cvs update can modify your files in a way that is hard to 

undo easily.  With this in mind it can be prudent to first check exactly what 

changes have been made since your last update.  To do this, use the cvs 'diff' 

command:

</p>

<p><tt>

root@users /usr/local/webcp# cd server/lib/

root@users /usr/local/webcp/server/lib# cvs diff freebsd-user.wcp.phps 



Index: freebsd-user.wcp.phps 

=================================================================== 

RCS file: /var/lib/cvsroot/webcp/server/lib/Attic/freebsd-user.wcp.phps,v 

retrieving revision 1.1 

diff -r1.1 freebsd-user.wcp.phps 

&lt;snip&gt;</tt></p>



<p>

This command allows you to see exactly what changes have been made to the file 

you execute the cvs 'diff' command on.  Note if you execute cvs 'diff' without 

a file argument, cvs will find diffs for every file in the current directory 

hierarchy - which can take a long time!

</p>



<p>

<a href="http://validator.w3.org/check/referer">

<img src="http://www.w3.org/Icons/valid-xhtml10" border="0"

	alt="Valid XHTML 1.0!" height="31" width="88" />

</a>

</p>



</body>

</html>



